Pyramid plots: Pyramid plots

Description

High-level functions that create pyramid plots.

Usage

PlotBPyramid(community, 
             level = floor(PreyAveragedTrophicLevel(community)),
             expected.levels,
             fill.missing.levels = TRUE,
             order.by.expected = TRUE,
             show.level.labels = TRUE, 
             xlab = Log10BLabel(community, name=expression(~sum(italic(B)))), 
             ylab = "", 
             xlim = NULL, 
             col = NULL, 
             text.col = 'black',
             main = CPS(community)$title,
             ...)
PlotNPyramid(community, 
             level = floor(PreyAveragedTrophicLevel(community)),
             expected.levels,
             fill.missing.levels = TRUE,
             order.by.expected = TRUE,
             show.level.labels = TRUE, 
             xlab = Log10NLabel(community, name=expression(~sum(italic(N)))),
             ylab = "", 
             xlim = NULL, 
             col = NULL, 
             text.col = 'black',
             main = CPS(community)$title,
             ...)

Arguments

community: an object of class Community
level: levels by which values are summed. Can be either the name of a node property, in which case it must meet the criteria of the properties parameter of NPS, or a vector of length NumberOfNodes that contains the levels.
expected.levels: the values that are expected to be in level; see Details for more information.
fill.missing.levels: if TRUE, values in expected.levels that are not present in level are shown in the pyramid.
order.by.expected: if TRUE then the levels are plotted in the order given in expected.levels.
show.level.labels: logical - if TRUE then values of level are shown to the left of the pyramid.
xlab: title of the x axis.
ylab: title of the y axis.
xlim: limits of the x axis.
col: fill colour; either a single colour a vector containing a colour per level.
text.col: colour for the text showing the log10-transformed sums in the blocks of the pyramid; ; either a single colour a vector containing a colour per level.
main: title of the plot.
...: other values to plot functions.

Author

Lawrence Hudson

Details

PlotBPyramid plots log10-transformed sum biomass abundance in each level and PlotNPyramid plots log10-transformed sum numerical abundance in each level.

expected.levels provides two behaviours. First, it provides error checking: an error is raised if values are in level that are not in expected.levels. Second, it interacts with fill.missing.levels and order.by.expected to control which levels are drawn and how. If fill.missing.levels is TRUE then values in expected.levels that are not present in level are shown on the pyramid plot. If order.by.level is TRUE then the levels are plotted in the order given in expected.levels. If level contains numbers then expected.levels defaults to a sequence of integers floor(min(level)):ceiling(max(level)). If level is `category' then expected.levels defaults to the intersection of values of `category' that are present in community and the usual Cheddar default values: `<unnamed>', `producer', `invertebrate', `vert.ecto', `vert.endo'.

Examples

Run this code

data(TL84)

# Use a large left-hand margin to show level text
reset.par <- par(mar=c(5,8,1,1))

# Using prey-averaged trophic level
PlotNPyramid(TL84)

# Using chain-averaged of trophic level
PlotNPyramid(TL84, level=floor(ChainAveragedTrophicLevel(TL84)))

# Show by category
PlotNPyramid(TL84, level='category')

# Taxonomic kingdoms as levels
PlotNPyramid(TL84, level='kingdom')

# Taxonomic kingdoms as levels, with a defined order
PlotNPyramid(TL84, level='kingdom', expected.levels=c("", "Plantae", 
             "Chromista","Bacteria","Protozoa","Animalia"))


# Compare the YthanEstuary and the TL84 datasets. YthanEstuary has nodes in 
# each of the categories whereas TL84 only has producer, invertebrate and 
# vert.ecto nodes. Show categories that are not present in TL84
par(mfrow=c(1,2))
data(YthanEstuary)
xlim <- range(c(Log10N(TL84), Log10N(YthanEstuary)), na.rm=TRUE)
PlotNPyramid(TL84, level='category', xlim=xlim, 
             expected.levels=c('', 'producer', 'invertebrate', 
                               'vert.ecto', 'vert.endo'))
PlotNPyramid(YthanEstuary, level='category',  xlim=xlim)
par(mfrow=c(1,1))


# For the BroadstoneStream dataset, the LongestTrophicLevel function returns 
# nodes in levels 1 and 7 to 10 but no nodes in levels 2 to 6. 
# By default all levels between the minimum and maximum are shown, so levels 
# 2 to 6 appear with no boxes.
data(BroadstoneStream)
PlotNPyramid(BroadstoneStream, 
             level=floor(LongestTrophicLevel(BroadstoneStream)))

# Set fill.missing.levels to FALSE to prevent levels 2 to 6 from being drawn.
PlotNPyramid(BroadstoneStream, 
             level=floor(LongestTrophicLevel(BroadstoneStream)), 
             fill.missing.levels=FALSE)

par(reset.par)